Creating context menu items

To create a menu item to save cat.jpg into the directory ~/downloads/i/cats, with ~/downloads as the default download directory, add the line i/cats.

.
i/dogs
i/cats // cute!
---
v/cats
:date:/:day:/foo
---
submenu
>mammals
>>i/cats // (alias: cute cats)
>>i/dogs
>i/others

~/downloads/
~/downloads/i/dogs
~/downloads/i/cats
---
~/downloads/v/cats
~/downloads/2000-01-01/01/foo
---
(submenu)
(submenu)
~/downloads/i/cats (shows up as "cute cats")
~/downloads/i/dogs
~/downloads/i/others

Comments and aliases

To add comments, add // to the end of a line. For example, cats // very cute!.

To change display names of menu items, add (alias: display name) to comments. For example, cats // very cute! (alias: cute cats). The menu item will then show "cute cats" instead of "cats".

Submenus

To create submenus, add >s to the line itself. An example can be seen above.

Note: You can only save relative to the default download directory. See the next guide for a workaround.

Saving outside the default download directory

The WebExtensions API does not allow files to be saved outside of the default download directory. A symlink inside the default download directory can be used to get around this limitation.

Invalid paths ( .. and /) are ignored. Files and directories with leading dots ( foo/.hidden) are considered invalid by Firefox and Chrome.

mklink /D C:\path\to\symlink D:\path\to\actual

ln -s /path/to/actual /path/to/symlink

Make sure the target directories actually exist, or the extension will silently fail to download.

Renaming downloads

Match downloads against regex patterns. When a download matches all patterns, rename it according to into:.

This renames all gif files to a UNIX timestamp.

fileext: gif
into: :unixdate:.:fileext:

cat.gif ➡ 1512136516.gif
 

Moving downloads into different directories

The following example moves all .gif files into the gifs subdirectory and renames the moved files to a timestamp.

fileext: gif
into: gifs/:unixdate:.:fileext:

cat.gif ➡ gifs/1512136516.gif
cat.jpg ✘ (no match)

Routing is relative to the selected menu item. When you download a cat gif using the images context menu, the above example will save it as ~/downloads/images/gif/946684800.gif.

This advanced example renames downloads based off captured regex groups — the stuff inside () — and moves them into different directories. capture: filename selects the filename’s capture groups, and finally into: renames the files based off them using :$1:, :$2:, and :$3:.

// Move downloads based off versions
filename: (.*)\.(v.)\.(tar|gz)
pageurl: example.com
capture: filename
into: :$2:/:$1:.:$3:

ubuntu.v1.tar ➡ v1/ubuntu.tar
debian.v2.gz  ➡ v2/debian.gz
debian.zip    ✘ (no match)